package org.apache.lucene.search;

/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import java.io.IOException;

import org.apache.lucene.search.BooleanClause.Occur;

/**
 * Expert: Common scoring functionality for different types of queries.
 *
 * <p>
 * A <code>Scorer</code> iterates over documents matching a
 * query in increasing order of doc Id.
 * </p>
 * <p>
 * Document scores are computed using a given <code>Similarity</code>
 * implementation.
 * </p>
 *
 * <p><b>NOTE</b>: The values Float.Nan,
 * Float.NEGATIVE_INFINITY and Float.POSITIVE_INFINITY are
 * not valid scores.  Certain collectors (eg {@link
 * TopScoreDocCollector}) will not properly collect hits
 * with these scores.
 */
public abstract class Scorer extends DocIdSetIterator {
    private final Similarity similarity;
    protected final Weight weight;

    /**
     * Constructs a Scorer
     * @param weight The scorers <code>Weight</code>.
     */
    protected Scorer(Weight weight) {
        this(null, weight);
    }

    /** Constructs a Scorer.
     * @param similarity The <code>Similarity</code> implementation used by this scorer.
     * @deprecated Use {@link #Scorer(Weight)} instead.
     */
    @Deprecated
    protected Scorer(Similarity similarity) {
        this(similarity, null);
    }

    /**
     * Constructs a Scorer
     * @param similarity The <code>Similarity</code> implementation used by this scorer.
     * @param weight The scorers <code>Weight</code>
     * @deprecated Use {@link #Scorer(Weight)} instead.
     */
    @Deprecated
    protected Scorer(Similarity similarity, Weight weight) {
        this.similarity = similarity;
        this.weight = weight;
    }

    /** Returns the Similarity implementation used by this scorer. 
     * @deprecated Store any Similarity you might need privately in your implementation instead.
     */
    @Deprecated
    public Similarity getSimilarity() {
        return this.similarity;
    }

    /** Scores and collects all matching documents.
     * @param collector The collector to which all matching documents are passed.
     */
    public void score(Collector collector) throws IOException {
        collector.setScorer(this);
        int doc;
        while ((doc = nextDoc()) != NO_MORE_DOCS) {
            collector.collect(doc);
        }
    }

    /**
     * Expert: Collects matching documents in a range. Hook for optimization.
     * Note, <code>firstDocID</code> is added to ensure that {@link #nextDoc()}
     * was called before this method.
     *
     * <p><b>NOTE:</b> Because of backwards compatibility, this method is still
     * declared as <b>protected</b>, but it is intended to be <b>public</b>,
     * because it's called from other classes (like BooleanScorer).
     * If you subclass {@code Scorer}, you should declare the overridden method
     * as public to ease transition to Lucene 4.0, where it will be public.</p>
     * 
     * @param collector
     *          The collector to which all matching documents are passed.
     * @param max
     *          Do not score documents past this.
     * @param firstDocID
     *          The first document ID (ensures {@link #nextDoc()} is called before
     *          this method.
     * @return true if more matching documents may remain.
     */
    protected boolean score(Collector collector, int max, int firstDocID) throws IOException {
        collector.setScorer(this);
        int doc = firstDocID;
        while (doc < max) {
            collector.collect(doc);
            doc = nextDoc();
        }
        return doc != NO_MORE_DOCS;
    }

    /** Returns the score of the current document matching the query.
     * Initially invalid, until {@link #nextDoc()} or {@link #advance(int)}
     * is called the first time, or when called from within
     * {@link Collector#collect}.
     */
    public abstract float score() throws IOException;

    /** Returns number of matches for the current document.
     *  This returns a float (not int) because
     *  SloppyPhraseScorer discounts its freq according to how
     *  "sloppy" the match was.
     *
     * @lucene.experimental */
    public float freq() throws IOException {
        throw new UnsupportedOperationException(this + " does not implement freq()");
    }

    /**
     * A callback to gather information from a scorer and its sub-scorers. Each
     * the top-level scorer as well as each of its sub-scorers are passed to
     * either one of the visit methods depending on their boolean relationship in
     * the query.
     * @lucene.experimental
     */
    public static abstract class ScorerVisitor<P extends Query, C extends Query, S extends Scorer> {
        /**
         * Invoked for all optional scorer 
         * 
         * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
         * @param child the query of the currently visited scorer
         * @param scorer the current scorer
         */
        public void visitOptional(P parent, C child, S scorer) {
        }

        /**
         * Invoked for all required scorer 
         * 
         * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
         * @param child the query of the currently visited scorer
         * @param scorer the current scorer
         */
        public void visitRequired(P parent, C child, S scorer) {
        }

        /**
         * Invoked for all prohibited scorer 
         * 
         * @param parent the parent query of the child query or <code>null</code> if the child is a top-level query
         * @param child the query of the currently visited scorer
         * @param scorer the current scorer
         */
        public void visitProhibited(P parent, C child, S scorer) {
        }
    }

    /**
     * Expert: call this to gather details for all sub-scorers for this query.
     * This can be used, in conjunction with a custom {@link Collector} to gather
     * details about how each sub-query matched the current hit.
     * 
     * @param visitor a callback executed for each sub-scorer
     * @lucene.experimental
     */
    public void visitScorers(ScorerVisitor<Query, Query, Scorer> visitor) {
        visitSubScorers(null, Occur.MUST/*must id default*/, visitor);
    }

    /**
     * {@link Scorer} subclasses should implement this method if the subclass
     * itself contains multiple scorers to support gathering details for
     * sub-scorers via {@link ScorerVisitor}
     * <p>
     * Note: this method will throw {@link UnsupportedOperationException} if no
     * associated {@link Weight} instance is provided to
     * {@link #Scorer(Weight)}
     * </p>
     * 
     * @lucene.experimental
     */
    protected void visitSubScorers(Query parent, Occur relationship, ScorerVisitor<Query, Query, Scorer> visitor) {
        if (weight == null)
            throw new UnsupportedOperationException();

        final Query q = weight.getQuery();
        switch (relationship) {
            case MUST:
                visitor.visitRequired(parent, q, this);
                break;
            case MUST_NOT:
                visitor.visitProhibited(parent, q, this);
                break;
            case SHOULD:
                visitor.visitOptional(parent, q, this);
                break;
        }
    }
}
